.TH std::weak_ptr 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::weak_ptr \- std::weak_ptr

.SH Synopsis
   Defined in header <memory>
   template< class T > class weak_ptr;  \fI(since C++11)\fP

   std::weak_ptr is a smart pointer that holds a non-owning ("weak") reference to an
   object that is managed by std::shared_ptr. It must be converted to std::shared_ptr
   in order to access the referenced object.

   std::weak_ptr models temporary ownership: when an object needs to be accessed only
   if it exists, and it may be deleted at any time by someone else, std::weak_ptr is
   used to track the object, and it is converted to std::shared_ptr to assume temporary
   ownership. If the original std::shared_ptr is destroyed at this time, the object's
   lifetime is extended until the temporary std::shared_ptr is destroyed as well.

   Another use for std::weak_ptr is to break reference cycles formed by objects managed
   by std::shared_ptr. If such cycle is orphaned (i.e., there are no outside shared
   pointers into the cycle), the shared_ptr reference counts cannot reach zero and the
   memory is leaked. To prevent this, one of the pointers in the cycle can be made
   weak.

.SH Member types

   Member type  Definition
   element_type T                       \fI(until C++17)\fP
                std::remove_extent_t<T> \fI(since C++17)\fP

.SH Member functions

   constructor   creates a new weak_ptr
                 \fI(public member function)\fP
   destructor    destroys a weak_ptr
                 \fI(public member function)\fP
   operator=     assigns the weak_ptr
                 \fI(public member function)\fP
.SH Modifiers
   reset         releases the ownership of the managed object
                 \fI(public member function)\fP
   swap          swaps the managed objects
                 \fI(public member function)\fP
.SH Observers
   use_count     returns the number of shared_ptr objects that manage the object
                 \fI(public member function)\fP
   expired       checks whether the referenced object was already deleted
                 \fI(public member function)\fP
   lock          creates a shared_ptr that manages the referenced object
                 \fI(public member function)\fP
   owner_before  provides owner-based ordering of weak pointers
                 \fI(public member function)\fP
   owner_hash    provides owner-based hashing of weak pointers
   (C++26)       \fI(public member function)\fP
   owner_equal   provides owner-based equal comparison of weak pointers
   (C++26)       \fI(public member function)\fP

.SH Non-member functions

   std::swap(std::weak_ptr) specializes the std::swap algorithm
   \fI(C++11)\fP                  \fI(function template)\fP

.SH Helper classes

   std::atomic<std::weak_ptr> atomic weak pointer
   (C++20)                    \fI(class template specialization)\fP

   Deduction guides \fI(since C++17)\fP

.SH Notes

   Like std::shared_ptr, a typical implementation of weak_ptr stores two pointers:

     * a pointer to the control block; and
     * the stored pointer of the shared_ptr it was constructed from.

   A separate stored pointer is necessary to ensure that converting a shared_ptr to
   weak_ptr and then back works correctly, even for aliased shared_ptrs. It is not
   possible to access the stored pointer in a weak_ptr without locking it into a
   shared_ptr.

           Feature-test macro          Value    Std                Feature
                                                      Enabling the use of std::weak_ptr
   __cpp_lib_smart_ptr_owner_equality 202306L (C++26) as keys in unordered associative
                                                      containers

.SH Example

   Demonstrates how lock is used to ensure validity of the pointer.


// Run this code

 #include <iostream>
 #include <memory>

 std::weak_ptr<int> gw;

 void observe()
 {
     std::cout << "gw.use_count() == " << gw.use_count() << "; ";
     // we have to make a copy of shared pointer before usage:
     if (std::shared_ptr<int> spt = gw.lock())
         std::cout << "*spt == " << *spt << '\\n';
     else
         std::cout << "gw is expired\\n";
 }

 int main()
 {
     {
         auto sp = std::make_shared<int>(42);
         gw = sp;

         observe();
     }

     observe();
 }

.SH Output:

 gw.use_count() == 1; *spt == 42
 gw.use_count() == 0; gw is expired

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to             Behavior as published              Correct behavior
   LWG 3001 C++17      element_type was not updated for array support updated

.SH See also

   unique_ptr smart pointer with unique object ownership semantics
   \fI(C++11)\fP    \fI(class template)\fP
   shared_ptr smart pointer with shared object ownership semantics
   \fI(C++11)\fP    \fI(class template)\fP
